Autenticação TypeScript: Padrões de Segurança de Tipos JWT para Aplicações Globais

No mundo interconectado de hoje, construir aplicações globais seguras e confiáveis é primordial. A autenticação, o processo de verificação da identidade de um usuário, desempenha um papel crítico na proteção de dados sensíveis e na garantia de acesso autorizado. JSON Web Tokens (JWTs) tornaram-se uma escolha popular para implementar a autenticação devido à sua simplicidade e portabilidade. Quando combinada com o poderoso sistema de tipos do TypeScript, a autenticação JWT pode ser tornada ainda mais robusta e manutenível, particularmente para projetos de grande escala e internacionais.

Por que Usar TypeScript para Autenticação JWT?

O TypeScript traz várias vantagens para a mesa ao construir sistemas de autenticação:

• Segurança de Tipos: A tipagem estática do TypeScript ajuda a detectar erros precocemente no processo de desenvolvimento, reduzindo o risco de surpresas em tempo de execução. Isso é crucial para componentes sensíveis à segurança, como a autenticação.
• Melhor Manutenibilidade do Código: Os tipos fornecem contratos claros e documentação, facilitando a compreensão, modificação e refatoração do código, especialmente em aplicações globais complexas onde vários desenvolvedores podem estar envolvidos.
• Melhor Autocompletar e Ferramentas de Código: IDEs que entendem TypeScript oferecem melhor autocompletar de código, navegação e ferramentas de refatoração, aumentando a produtividade do desenvolvedor.
• Redução de Código Repetitivo: Recursos como interfaces e genéricos podem ajudar a reduzir código repetitivo e melhorar a reutilização de código.

Entendendo JWTs

Um JWT é um meio compacto e seguro para URL de representar claims a serem transferidos entre duas partes. Ele consiste em três partes:

1. Header: Especifica o algoritmo e o tipo de token.
2. Payload: Contém claims, como ID do usuário, papéis e tempo de expiração.
3. Signature: Garante a integridade do token usando uma chave secreta.

JWTs são tipicamente usados para autenticação porque podem ser facilmente verificados no lado do servidor sem a necessidade de consultar um banco de dados para cada requisição. No entanto, armazenar informações sensíveis diretamente no payload do JWT geralmente não é recomendado.

Implementando Autenticação JWT Type-Safe em TypeScript

Vamos explorar alguns padrões para construir sistemas de autenticação JWT type-safe em TypeScript.

1. Definindo Tipos de Payload com Interfaces

Comece definindo uma interface que representa a estrutura do seu payload JWT. Isso garante que você tenha segurança de tipos ao acessar claims dentro do token.

interface JwtPayload {
  userId: string;
  email: string;
  roles: string[];
  iat: number; // Issued At (timestamp)
  exp: number; // Expiration Time (timestamp)
}

Esta interface define a forma esperada do payload JWT. Incluímos claims JWT padrão como `iat` (emitido em) e `exp` (tempo de expiração) que são cruciais para gerenciar a validade do token. Você pode adicionar quaisquer outras claims relevantes para sua aplicação, como papéis ou permissões do usuário. É uma boa prática limitar as claims apenas às informações necessárias para minimizar o tamanho do token e melhorar a segurança.

Exemplo: Lidando com Papéis de Usuário em uma Plataforma Global de E-commerce

Considere uma plataforma de e-commerce que atende clientes em todo o mundo. Diferentes usuários têm papéis diferentes:

• Admin: Acesso total para gerenciar produtos, usuários e pedidos.
• Vendedor: Pode adicionar e gerenciar seus próprios produtos.
• Cliente: Pode navegar e comprar produtos.

O array `roles` em `JwtPayload` pode ser usado para representar esses papéis. Você pode expandir a propriedade `roles` para uma estrutura mais complexa, representando os direitos de acesso do usuário de forma granular. Por exemplo, você pode ter uma lista de países em que o usuário pode operar como vendedor, ou um array de lojas às quais o usuário tem acesso administrativo.

2. Criando um Serviço JWT Tipado

Crie um serviço que lide com a criação e verificação de JWT. Este serviço deve usar a interface `JwtPayload` para garantir a segurança de tipos.

import jwt from 'jsonwebtoken';

const JWT_SECRET = process.env.JWT_SECRET || 'your-secret-key'; // Armazene com segurança!

class JwtService {
  static sign(payload: Omit, expiresIn: string = '1h'): string {
    const now = Math.floor(Date.now() / 1000);
    const payloadWithTimestamps: JwtPayload = {
        ...payload,
        iat: now,
        exp: now + parseInt(expiresIn) * 60 * 60,
    };
    return jwt.sign(payloadWithTimestamps, JWT_SECRET);
  }

  static verify(token: string): JwtPayload | null {
    try {
      const decoded = jwt.verify(token, JWT_SECRET) as JwtPayload;
      return decoded;
    } catch (error) {
      console.error('JWT verification error:', error);
      return null;
    }
  }
}

Este serviço fornece dois métodos:

• `sign()`: Cria um JWT a partir de um payload. Ele recebe um `Omit` para garantir que `iat` e `exp` sejam gerados automaticamente. É importante armazenar `JWT_SECRET` com segurança, idealmente usando variáveis de ambiente e uma solução de gerenciamento de segredos.
• `verify()`: Verifica um JWT e retorna o payload decodificado se for válido, ou `null` se for inválido. Usamos uma afirmação de tipo `as JwtPayload` após a verificação, o que é seguro porque o método `jwt.verify` lança um erro (capturado no bloco `catch`) ou retorna um objeto que corresponde à estrutura de payload que definimos.

Considerações Importantes de Segurança:

• Gerenciamento de Chave Secreta: Nunca codifique sua chave secreta JWT em seu código. Use variáveis de ambiente ou um serviço dedicado de gerenciamento de segredos. Rotacione as chaves regularmente.
• Seleção de Algoritmo: Escolha um algoritmo de assinatura forte, como HS256 ou RS256. Evite algoritmos fracos como `none`.
• Expiração do Token: Defina tempos de expiração apropriados para seus JWTs para limitar o impacto de tokens comprometidos.
• Armazenamento do Token: Armazene JWTs com segurança no lado do cliente. As opções incluem cookies HTTP-only ou armazenamento local com precauções apropriadas contra ataques XSS.

3. Protegendo Endpoints de API com Middleware

Crie middleware para proteger seus endpoints de API verificando o JWT no cabeçalho `Authorization`.

import { Request, Response, NextFunction } from 'express';

interface RequestWithUser extends Request {
  user?: JwtPayload;
}

function authenticate(req: RequestWithUser, res: Response, next: NextFunction) {
  const authHeader = req.headers.authorization;

  if (!authHeader) {
    return res.status(401).json({ message: 'Unauthorized' });
  }

  const token = authHeader.split(' ')[1]; // Assumindo token Bearer
  const decoded = JwtService.verify(token);

  if (!decoded) {
    return res.status(401).json({ message: 'Invalid token' });
  }

  req.user = decoded;
  next();
}

export default authenticate;

Este middleware extrai o JWT do cabeçalho `Authorization`, o verifica usando o `JwtService` e anexa o payload decodificado ao objeto `req.user`. Também definimos uma interface `RequestWithUser` para estender a interface `Request` padrão do Express.js, adicionando uma propriedade `user` do tipo `JwtPayload | undefined`. Isso fornece segurança de tipos ao acessar as informações do usuário em rotas protegidas.

Exemplo: Lidando com Fusos Horários em uma Aplicação Global

Imagine que sua aplicação permite que usuários de diferentes fusos horários agendem eventos. Você pode querer armazenar o fuso horário preferido do usuário no payload JWT para exibir corretamente os horários dos eventos. Você poderia adicionar uma claim `timeZone` à interface `JwtPayload`:

interface JwtPayload {
  userId: string;
  email: string;
  roles: string[];
  timeZone: string; // e.g., 'America/Los_Angeles', 'Asia/Tokyo'
  iat: number;
  exp: number;
}

Em seguida, em seu middleware ou manipuladores de rota, você pode acessar `req.user.timeZone` para formatar datas e horas de acordo com a preferência do usuário.

4. Usando o Usuário Autenticado em Manipuladores de Rota

Em seus manipuladores de rota protegidos, você agora pode acessar as informações do usuário autenticado através do objeto `req.user`, com segurança de tipos completa.

import express, { Request, Response } from 'express';
import authenticate from './middleware/authenticate';

const app = express();

app.get('/profile', authenticate, (req: Request, res: Response) => {
  const user = (req as any).user; // ou use RequestWithUser
  res.json({ message: `Hello, ${user.email}!`, userId: user.userId });
});

Este exemplo demonstra como acessar o e-mail e o ID do usuário autenticado do objeto `req.user`. Como definimos a interface `JwtPayload`, o TypeScript conhece a estrutura esperada do objeto `user` e pode fornecer verificação de tipos e autocompletar código.

5. Implementando Controle de Acesso Baseado em Papel (RBAC)

Para um controle de acesso mais detalhado, você pode implementar RBAC com base nos papéis armazenados no payload JWT.

function authorize(roles: string[]) {
  return (req: RequestWithUser, res: Response, next: NextFunction) => {
    const user = req.user;

    if (!user || !user.roles.some(role => roles.includes(role))) {
      return res.status(403).json({ message: 'Forbidden' });
    }

    next();
  };
}

Este middleware `authorize` verifica se os papéis do usuário incluem algum dos papéis exigidos. Caso contrário, ele retorna um erro 403 Forbidden.

app.get('/admin', authenticate, authorize(['admin']), (req: Request, res: Response) => {
  res.json({ message: 'Welcome, Admin!' });
});

Este exemplo protege a rota `/admin`, exigindo que o usuário tenha o papel de `admin`.

Exemplo: Lidando com Diferentes Moedas em uma Aplicação Global

Se sua aplicação lida com transações financeiras, você pode precisar suportar várias moedas. Você pode armazenar a moeda preferida do usuário no payload JWT:

interface JwtPayload {
  userId: string;
  email: string;
  roles: string[];
  currency: string; // e.g., 'USD', 'EUR', 'JPY'
  iat: number;
  exp: number;
}

Em seguida, na sua lógica de back-end, você pode usar `req.user.currency` para formatar preços e realizar conversões de moeda conforme necessário.

6. Tokens de Atualização

JWTs são de curta duração por design. Para evitar exigir que os usuários façam login com frequência, implemente tokens de atualização. Um token de atualização é um token de longa duração que pode ser usado para obter um novo token de acesso (JWT) sem exigir que o usuário insira suas credenciais novamente. Armazene tokens de atualização com segurança em um banco de dados e associe-os ao usuário. Quando o token de acesso de um usuário expirar, ele poderá usar o token de atualização para solicitar um novo. Este processo precisa ser implementado cuidadosamente para evitar vulnerabilidades de segurança.

Técnicas Avançadas de Segurança de Tipos

1. Uniões Discriminadas para Controle Granular

Às vezes, você pode precisar de diferentes payloads JWT com base no papel do usuário ou no tipo de requisição. Uniões discriminadas podem ajudá-lo a alcançar isso com segurança de tipos.

interface AdminJwtPayload {
  type: 'admin';
  userId: string;
  email: string;
  roles: string[];
  iat: number;
  exp: number;
}

interface UserJwtPayload {
  type: 'user';
  userId: string;
  email: string;
  iat: number;
  exp: number;
}

type JwtPayload = AdminJwtPayload | UserJwtPayload;

function processToken(payload: JwtPayload) {
  if (payload.type === 'admin') {
    console.log('Admin email:', payload.email); // Acesso seguro ao e-mail
  } else {
    // payload.email não é acessível aqui porque o tipo é 'user'
    console.log('User ID:', payload.userId);
  }
}

Este exemplo define dois tipos de payload JWT diferentes, `AdminJwtPayload` e `UserJwtPayload`, e os combina em uma união discriminada `JwtPayload`. A propriedade `type` atua como um discriminador, permitindo que você acesse propriedades com segurança com base no tipo de payload.

2. Genéricos para Lógica de Autenticação Reutilizável

Se você tiver vários esquemas de autenticação com diferentes estruturas de payload, poderá usar genéricos para criar lógica de autenticação reutilizável.

interface BaseJwtPayload {
  userId: string;
  iat: number;
  exp: number;
}

function verifyToken(token: string): T | null {
  try {
    const decoded = jwt.verify(token, JWT_SECRET) as T;
    return decoded;
  } catch (error) {
    console.error('JWT verification error:', error);
    return null;
  }
}

const adminToken = verifyToken('admin-token');
if (adminToken) {
  console.log('Admin email:', adminToken.email);
}

Este exemplo define uma função `verifyToken` que recebe um tipo genérico `T` estendendo `BaseJwtPayload`. Isso permite verificar tokens com diferentes estruturas de payload, garantindo ao mesmo tempo que todos eles tenham pelo menos as propriedades `userId`, `iat` e `exp`.

Considerações para Aplicações Globais

Ao construir sistemas de autenticação para aplicações globais, considere o seguinte:

• Localização: Garanta que as mensagens de erro e os elementos da interface do usuário sejam localizados para diferentes idiomas e regiões.
• Fusos Horários: Lide corretamente com fusos horários ao definir tempos de expiração de token e exibir datas e horas aos usuários.
• Privacidade de Dados: Cumpra regulamentos de privacidade de dados como GDPR e CCPA. Minimize a quantidade de dados pessoais armazenados em JWTs.
• Acessibilidade: Projete seus fluxos de autenticação para serem acessíveis a usuários com deficiência.
• Sensibilidade Cultural: Esteja ciente das diferenças culturais ao projetar interfaces de usuário e fluxos de autenticação.

Conclusão

Ao aproveitar o sistema de tipos do TypeScript, você pode construir sistemas de autenticação JWT robustos e manuteníveis para aplicações globais. Definir tipos de payload com interfaces, criar serviços JWT tipados, proteger endpoints de API com middleware e implementar RBAC são passos essenciais para garantir segurança e segurança de tipos. Ao considerar considerações de aplicações globais como localização, fusos horários, privacidade de dados, acessibilidade e sensibilidade cultural, você pode criar experiências de autenticação que são inclusivas e fáceis de usar para um público internacional diversificado. Lembre-se de sempre priorizar as melhores práticas de segurança ao lidar com JWTs, incluindo gerenciamento seguro de chaves, seleção de algoritmos, expiração de token e armazenamento de token. Abrace o poder do TypeScript para construir sistemas de autenticação seguros, escaláveis e confiáveis para suas aplicações globais.